<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Compiler Invocation
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot029.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot028.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot031.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc61">6.2</A>&nbsp;&nbsp;Compiler Invocation</H2><UL>
<LI><A HREF="umsroot030.html#toc33">Source Files</A>
<LI><A HREF="umsroot030.html#toc34">Main Compiler Options</A>
</UL>


The compiler is usually invoked by calling one of the following built-in
predicates:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<A HREF="../bips/kernel/compiler/compile-1.html"><B>compile(Source)</B></A><A NAME="@default200"></A><DD CLASS="dd-description">
<A NAME="@default201"></A>
This is the standard compiler predicate.
Source is usually a file name, other forms are detailed below.
The contents of the file is compiled with the default compiler options.<BR>
<BR>
<DT CLASS="dt-description"><A HREF="../bips/kernel/compiler/compile-2.html"><B>compile(Source, Options)</B></A><A NAME="@default202"></A><DD CLASS="dd-description">
<A NAME="@default203"></A>
This is the standard compiler predicate.
Source is usually a file name, other forms are detailed below.
Options is a list of options to control the compilation process, see details below.<BR>
<BR>
<DT CLASS="dt-description"><A HREF="../bips/kernel/compiler/D-2.html"><B>[File1,...,FileN]</B></A><A NAME="@default204"></A><DD CLASS="dd-description">
<A NAME="@default205"></A>
This predicate can be used as a shorthand for the
<A HREF="../bips/kernel/compiler/compile-1.html"><B>compile/1</B></A><A NAME="@default206"></A>
predicate.
It accepts a list of files, which can be source files or precompiled files.<BR>
<BR>
<DT CLASS="dt-description"><A HREF="../bips/kernel/compiler/compile_stream-1.html"><B>compile_stream(Stream)</B></A><A NAME="@default207"></A><DD CLASS="dd-description">
<A NAME="@default208"></A>
This predicate compiles a given, open stream up to its end
or to the <TT>end_of_file</TT> clause.
It can be used when the input file is already open,
e.g. when the beginning of the file does not contain
compiler input.<BR>
<BR>
<DT CLASS="dt-description"><A HREF="../bips/kernel/compiler/compile_stream-2.html"><B>compile_stream(Stream,Options)</B></A><A NAME="@default209"></A><DD CLASS="dd-description">
<A NAME="@default210"></A>
Like compile_stream/1 but with options list.<BR>
<BR>
<DT CLASS="dt-description"><A HREF="../bips/kernel/compiler/compile_term-1.html"><B>compile_term(Clauses)</B></A><A NAME="@default211"></A><DD CLASS="dd-description">
<A NAME="@default212"></A>
This predicate is used to compile a given term,
usually a list of clauses and directives.
Unlike <A HREF="../bips/kernel/dynamic/assert-1.html"><B>assert/1</B></A><A NAME="@default213"></A> it compiles
a static procedure,
and so it can be used to compile a procedure which is dynamically
created and then used as a static one.<BR>
<BR>
<DT CLASS="dt-description"><A HREF="../bips/kernel/compiler/compile_term-2.html"><B>compile_term(Clauses,Options)</B></A><A NAME="@default214"></A><DD CLASS="dd-description">
<A NAME="@default215"></A>
Like compile_stream/2 but with options list.
</DL>
When using a development environment like
<A NAME="@default216"></A>
<A NAME="@default217"></A>
TkEclipse or Saros, the compiler is usually invoked implicitly via
menu options or buttons.<BR>
<BR>
<A NAME="toc33"></A>
<H3 CLASS="subsection"><A NAME="htoc62">6.2.1</A>&nbsp;&nbsp;Source Files</H3>

Program source is usually contained in files. The recommended file
<A NAME="@default218"></A>
<A NAME="@default219"></A>
suffixes (extensions) are
<UL CLASS="itemize"><LI CLASS="li-itemize">
<B>.ecl</B> for ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> specific source
<LI CLASS="li-itemize"><B>.pl</B> for Prolog source
</UL>
To compile a source files solver.ecl, any of the following forms is
acceptable:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
?- compile('solver.ecl').
?- compile("solver.ecl").
?- compile("/home/joe/solver.ecl").
?- compile("/home/joe/solver").
?- compile(solver).
</PRE></BLOCKQUOTE>
File names need to be single quoted (atom) or double quoted (string)
if they contain punctuation, blank space, or start with an upper case letter.
The <B>.ecl</B> extension can be omitted as long as no file without extension
is present. A <B>.pl</B> extension can be omitted as long as no file without
extension and no file with <B>.ecl</B> extension is present. The list of
accepted suffixes and their precedence is given by the global flag
<A NAME="@default220"></A>
<B>prolog_suffix</B>, see
<A HREF="../bips/kernel/compiler/get_flag-3.html"><B>get_flag/3</B></A><A NAME="@default221"></A>.<BR>
<BR>
The following shorthands can be used, but note that the last two forms
will load precompiled .eco files by preference, should they be present:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
?- ['solver.ecl'].
?- ["solver.ecl"].
?- ["/home/joe/solver.ecl"].
?- ["/home/joe/solver"].
?- [solver].
</PRE></BLOCKQUOTE>
If the source is given as library(Name), the predicates looks for the file
in the directories from the global flag <B>library_path</B>.<BR>
<BR>
If File is the special atom 'user', the source will be taken from
the current 'input' stream, i.e. will usually generate a prompt
at which clauses can be typed in. In this case, input must be
terminated either by typing CTRL-D (on Unix), CTRL-Z + RETURN
(on Windows), or with the single atom end_of_file, followed by
a fullstop/period.
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
?- [user].
 main :- writeln(hello).
^D
tty        compiled 72 bytes in 0.01 seconds
Yes (0.01 cpu)
?- main.
hello
Yes (0.00s cpu)
</PRE></BLOCKQUOTE>
If File is the special form stream(Stream), then the source is taken
from the given stream (which must be already opened). The stream
content is compiled until the end of stream (or the end_of_file marker).
Using this feature, any ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> stream (file, socket, tty, string,
queue, pipe) can be used as the source for program text.<BR>
<BR>
<A NAME="toc34"></A>
<H3 CLASS="subsection"><A NAME="htoc63">6.2.2</A>&nbsp;&nbsp;Main Compiler Options</H3>

The following compiler options affect the generated code:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>debug</B><DD CLASS="dd-description">
 This option (<B>off</B>/<B>on</B>) determines whether the resulting code contains
 debugging information. If <B>off</B>, subgoals of the compiled predicates will
 not be visible to the debugger, the code will be significantly smaller,
 and slightly faster.
 The default value is taken from the global flag <B>debug_compile</B>.
 The setting can be changed via a pragma (debug/nodebug) in the code.<BR>
<BR>
<DT CLASS="dt-description"><B>opt_level:</B><DD CLASS="dd-description">
 Currently the integer 0 or 1, with 1 the default. Setting this to 0
 will disable certain compiler optimizations and usually reduce performance.
 The setting can be changed via an opt_level(Level) pragma in the code.
</DL>
The following options determine what is being done with the compilation result:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>load:</B><DD CLASS="dd-description">
 Determines whether the generated code is immediately loaded into memory,
 ready for execution. Values for the 'load' option are:
 <DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
 <B>all (default)</B><DD CLASS="dd-description">
 Load and replace code in memory, create/re-create all modules,
	interpret pragmas, and execute all directives and queries.
 <DT CLASS="dt-description"><B>none</B><DD CLASS="dd-description">
 Do not load any code into memory, do not execute queries,
	but interpret pragmas and execute directives.
 Do not re-create modules, but create new ones and erase them
 again after compilation.
 <DT CLASS="dt-description"><B>new</B><DD CLASS="dd-description">
 Do not overwrite any code in memory, but load new predicates.
 Do not execute queries, but interpret pragmas and execute directives.
 Do not re-create modules, but create new ones and erase them
 again after compilation. For existing modules, erase pragmas.
 </DL><BR>
<BR>
<DT CLASS="dt-description"><B>output:</B><DD CLASS="dd-description">
 The abstract machine code which is the result of the compilation can
 be output in various forms. Possible values are:
 <DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
 <B>none (default)</B><DD CLASS="dd-description">
 no output (but code may be loaded, see load option),
 <DT CLASS="dt-description"><B>eco</B><DD CLASS="dd-description">
 output compiled code in eco format to input file with .eco suffix
 This format can be loaded using ensure_loaded/1 or the compiler
 itself.
 <DT CLASS="dt-description"><B>eco(File)</B><DD CLASS="dd-description">
 output compiled code in eco format to File.
 <DT CLASS="dt-description"><B>asm</B><DD CLASS="dd-description">
 output compiled code in asm format to input file with .asm suffix.
 This format represents the code as WAM code that can be loaded back
 into ECLiPSe using the assembler (lib(asm)). 
 <DT CLASS="dt-description"><B>asm(File)</B><DD CLASS="dd-description">
 output compiled code in asm format to File.
 </DL><BR>
<BR>
<DT CLASS="dt-description"><B>outdir:</B><DD CLASS="dd-description">
 Value is the destination directory for all output files.
 The default is the empty string "", meaning that all output files
 go into the same directory as the corresponding input file.
</DL>
For other options see
<A HREF="../bips/kernel/compiler/compile-2.html"><B>compile/2</B></A><A NAME="@default222"></A>.<BR>
<BR>
For example, to compile a program without debugging support directly into
memory, use
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
?- compile(myprogram, [debug:off]).
</PRE></BLOCKQUOTE>
The following command will create a precompiled file myprogram.eco from a
source file called myprogram.ecl (or myprogram.pl):
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
?- compile(myprogram, [output:eco]).
</PRE></BLOCKQUOTE>
<HR>
<A HREF="umsroot029.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot028.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot031.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
